<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::transport::struc::Struct_builder Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Public API.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport.html">transport</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport_1_1struc.html">struc</a></li><li class="navelem"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#nested-classes">Classes</a> &#124;
<a href="#pub-types">Public Types</a> &#124;
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="classipc_1_1transport_1_1struc_1_1Struct__builder-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::transport::struc::Struct_builder Class Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A documentation-only <em>concept</em> defining the behavior of an object capable of zero-copy-serializing, similar to <code>capnp::MessageBuilder</code> but geared to transmission over pipe-like IPC transports.  
 <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#details">More...</a></p>

<p><code>#include &lt;serializer.hpp&gt;</code></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html">Config</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Copy-ctible, copy-assignable, default-ctible type &ndash; informally, cheaply copyable and likely an <em>aggregate</em> <code>struct</code> &ndash; objects of which store data that <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> main ctor knows how to interpret as knobs controlling its behavior.  <a href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-types" name="pub-types"></a>
Public Types</h2></td></tr>
<tr class="memitem:ab90424897efed06ffc6b0884761fb31f"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f">Session</a> = unspecified</td></tr>
<tr class="memdesc:ab90424897efed06ffc6b0884761fb31f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Type objects of which specify to <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> the opposing recipient for which the serialization is intended; <a class="el" href="structipc_1_1transport_1_1struc_1_1Null__session.html" title="Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder...">Null_session</a> if no information is necessary to specify this.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f">More...</a><br /></td></tr>
<tr class="separator:ab90424897efed06ffc6b0884761fb31f"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a460aa187c0aaa5adfb81ecc902c7eca9"><td class="memItemLeft" align="right" valign="top"><a id="a460aa187c0aaa5adfb81ecc902c7eca9" name="a460aa187c0aaa5adfb81ecc902c7eca9"></a>
&#160;</td><td class="memItemRight" valign="bottom"><b>Struct_builder</b> ()</td></tr>
<tr class="memdesc:a460aa187c0aaa5adfb81ecc902c7eca9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Default ctor, leaving <code>*this</code> in a state only suitable for destruction or being moved-to. <br /></td></tr>
<tr class="separator:a460aa187c0aaa5adfb81ecc902c7eca9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad98eba0fc5a8b377253eac797a9a117e"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ad98eba0fc5a8b377253eac797a9a117e">Struct_builder</a> (const <a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html">Config</a> &amp;config) <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a>(const <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;)=delete</td></tr>
<tr class="memdesc:ad98eba0fc5a8b377253eac797a9a117e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Main ctor, creating a new builder according to the knobs in <code><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a> config</code> arg.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ad98eba0fc5a8b377253eac797a9a117e">More...</a><br /></td></tr>
<tr class="separator:ad98eba0fc5a8b377253eac797a9a117e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a2c413c604b1d6abf63ce1589367dd772"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a2c413c604b1d6abf63ce1589367dd772">Struct_builder</a> (<a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a2c413c604b1d6abf63ce1589367dd772"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-constructs <code>*this</code> to be equal to <code>src</code>, while <code>src</code> becomes as-if defaulted-cted.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a2c413c604b1d6abf63ce1589367dd772">More...</a><br /></td></tr>
<tr class="separator:a2c413c604b1d6abf63ce1589367dd772"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a008f6b6456a4b2dab63cdda5f9e4cfe5"><td class="memItemLeft" align="right" valign="top"><a id="a008f6b6456a4b2dab63cdda5f9e4cfe5" name="a008f6b6456a4b2dab63cdda5f9e4cfe5"></a>
&#160;</td><td class="memItemRight" valign="bottom"><b>~Struct_builder</b> ()</td></tr>
<tr class="memdesc:a008f6b6456a4b2dab63cdda5f9e4cfe5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destructor. Do not use <code>*payload_msg_builder()</code> or any copies thereof past this. <br /></td></tr>
<tr class="separator:a008f6b6456a4b2dab63cdda5f9e4cfe5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a1899e36ae85a208f3208adfaeb5f0000"><td class="memItemLeft" align="right" valign="top"><a id="a1899e36ae85a208f3208adfaeb5f0000" name="a1899e36ae85a208f3208adfaeb5f0000"></a>
<a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><b>operator=</b> (const <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;)=delete</td></tr>
<tr class="memdesc:a1899e36ae85a208f3208adfaeb5f0000"><td class="mdescLeft">&#160;</td><td class="mdescRight">Disallow copy assignment. <br /></td></tr>
<tr class="separator:a1899e36ae85a208f3208adfaeb5f0000"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a708a66e9598c75a1f54828a4805da4f0"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a708a66e9598c75a1f54828a4805da4f0">operator=</a> (<a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a708a66e9598c75a1f54828a4805da4f0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-assigns <code>*this</code> to be equal to <code>src</code>, while <code>src</code> becomes as-if defaulted-cted; or no-op if <code>&amp;src == this</code>.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a708a66e9598c75a1f54828a4805da4f0">More...</a><br /></td></tr>
<tr class="separator:a708a66e9598c75a1f54828a4805da4f0"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9a4b9587c162f85ad4d3e0a5fad8dffb"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespaceipc_1_1transport_1_1struc.html#a52405569bf63eaef55f3c2435c885abc">Capnp_msg_builder_interface</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb">payload_msg_builder</a> ()</td></tr>
<tr class="memdesc:a9a4b9587c162f85ad4d3e0a5fad8dffb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Pointer to the payload <a class="el" href="namespaceipc_1_1transport_1_1struc.html#a52405569bf63eaef55f3c2435c885abc" title="Alias for capnp&#39;s MessageBuilder interface. Rationale: as part of our API, we use our identifier styl...">Capnp_msg_builder_interface</a>, suitable for mutation by the user.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb">More...</a><br /></td></tr>
<tr class="separator:a9a4b9587c162f85ad4d3e0a5fad8dffb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:af5085934123f075c6d0701e9e45e4bcc"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc">emit_serialization</a> (<a class="el" href="namespaceipc_1_1transport_1_1struc.html#a82a69eaa39cbe8a002de1266f1cbb5cb">Segment_ptrs</a> *target_blobs, const <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f">Session</a> &amp;session, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0) const</td></tr>
<tr class="memdesc:af5085934123f075c6d0701e9e45e4bcc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the serialization in the form of a sequence of 1+ pointers to <code>Blob</code>s which are guaranteed to remain valid and unchanged until <code>*this</code> is destroyed, or the contents are further mutated via <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a>.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc">More...</a><br /></td></tr>
<tr class="separator:af5085934123f075c6d0701e9e45e4bcc"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae1516b0d68c48f2e13baf6aca366ac6c"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ae1516b0d68c48f2e13baf6aca366ac6c">n_serialization_segments</a> () const</td></tr>
<tr class="memdesc:ae1516b0d68c48f2e13baf6aca366ac6c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns what <code>target_blobs.size()</code> would return after calling <code>emit_serialization(&amp;target_blobs)</code> (with an empty <code>target_blobs</code> going-in), right now.  <a href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ae1516b0d68c48f2e13baf6aca366ac6c">More...</a><br /></td></tr>
<tr class="separator:ae1516b0d68c48f2e13baf6aca366ac6c"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A documentation-only <em>concept</em> defining the behavior of an object capable of zero-copy-serializing, similar to <code>capnp::MessageBuilder</code> but geared to transmission over pipe-like IPC transports. </p>
<p >At its simplest it is conceptually identical to <code>MessageBuilder</code> but, crucially, also allows for the (optional) 2-tier architecture wherein only a small handle is transmitted over an IPC pipe, while the user-controlled tree is stored in a single central location (most likely in shared memory) and is itself never copied. The following discussion assumes sophisticated familiarity with capnp (Cap'n Proto).</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a>, the counterpart concept.</dd></dl>
<p>The above description may sound quite a lot like the capnp-supplied <code>virtual</code> interface, <code>capnp::MessageBuilder</code>. And some of this concept's most prominent impls have conceptual counterparts in the implementing classes of <code>MessageBuilder</code>; for example <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a> evokes <code>capnp::MallocMessageBuilder</code> (and in fact internally uses a custom <code>MessageBuilder</code> quite similar to <code>MallocMessageBuilder</code>).</p>
<p >Indeed, at its simplest, <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> is conceptually similar to <code>capnp::MessageBuilder</code>:</p><ul>
<li>It must store a concretely-typed <code>MessageBuilder</code> that the user would mutate via <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a>, which returns a pointer to said <code>MessageBuilder</code>. One would typically mutate it via <code>-&gt;initRoot&lt;SomeUserSchema&gt;()</code> and so on. Through this one can set the structured data within the data structure.</li>
<li>As one does so, the payload bits are set (by capnp-generated code) in zero-copy fashion inside 1+ segments somewhere in RAM (or other vaddr-mapped storage), without any user intervention outside of the actual capnp mutator calls.</li>
<li>One can then obtain the resulting serialization &ndash; consisting of 1+ segments in RAM. <code>MessageBuilder::getSegmentsForOutput()</code> is how it's done in <code>MessageBuilder</code>; while we have <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a>.</li>
</ul>
<p >Ultimately, in fact, any <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> is always implemented internally as a wrapper around one <code>MessageBuilder</code> or another (quite possibly a custom one also implemented by us).</p>
<p >So why does <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> exist, outside of cosmetic niceties? Answer: It is designed around (the possiblity of) two-tier serialization (discussed in "Copying versus zero-copy" below), namely for SHM-based IPC. <code>MessageBuilder</code>, alone, does not supply the necessary facilities to make the SHM/two-tier use-case easy; we do. A good way of looking at it is: <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> allows one to combine two <code>capnp::MessageBuilder</code>s, using one for user-facing mutation pre-transmission-over-IPC; and the other <code>MessageBuilder</code> for the tiny SHM-handle that's copied over at transmission-over-IPC time. <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a> provides access to the user-mutating; <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> provides access to the IPC-transmissible bits. When the serialization strategy is 1-tier, <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> is essentially isomorphic to <code>MessageBuilder</code>. When it is 2-tier, it adds significant conceptual value.</p>
<p >In any case a <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> formally works as follows.</p><ul>
<li>Construct it via <code>Struct_builder(const Struct_builder::Config&amp;)</code> ctor form, where <a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Struct_builder::Config</a> is a small (cheaply-copyable) type storing a few knobs controlling <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> behavior. (It exists to be able to easily store the same set of knob values to keep reusing it, as well to ease generic programming. The knob set for one <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> impl may hugely differ from another's. Informally, <a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a> is likely to be an <em>aggregate</em> <code>struct</code> hence aggregate-initializable (e.g., <code><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a> c{ knob1_val, knob2_val };</code>).<ul>
<li>This implies that each <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> impl shall feature this ctor form, such that it is possible/advised to pass the same (equal by value) <a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a> as args each time with no ill effects within reason.</li>
<li><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> must also be efficiently move-constructible and move-assignable but not copyable.</li>
</ul>
</li>
<li>Call <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a> which returns a <code>MessageBuilder*</code>; mutate the pointee as usual (likely <code>initRoot&lt;SomeUserSchema&gt;()</code> and so on).</li>
<li>Call <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a>. This emits a <a class="el" href="namespaceipc_1_1transport_1_1struc.html#a82a69eaa39cbe8a002de1266f1cbb5cb" title="Sequence of 1+ Blob pointers to blobs which must stay alive while these pointers may be dereferenced,...">Segment_ptrs</a> container which is basically a list of <em>pointers</em> to <code>flow::util::Blob</code> (which is much like <code>vector&lt;uint8_t&gt;</code>), where each <code>Blob</code> therein is stored within <code>*this</code> until destruction.</li>
<li>Transmit each <code>Blob</code>, in order, by copying into a transport (e.g., by using a <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>). Note that the transport must be capable of transmitting these blobs while maintaining ordering and boundaries and without barfing due to anything, including a single blob, being too large. (It is up to the <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> impl to document any such limitations it might have.)</li>
<li>(<code>*this</code> can now be destroyed.)</li>
<li>Use the counterpart <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> on the other side of this transport to obtain access to this serialization. See <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> doc header.</li>
</ul>
<p >The following is an optional continuation of the lifecycle of a <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a>. There are two varieties: read-only and read/write. The read-only lifecycle continuation is as follows:</p><ul>
<li>Call <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> again.</li>
<li>Transmit the emitted <code>Blob</code>s again into some transport again (the same one, a different one, whatever).</li>
<li>Again use the counterpart <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> on the other side of this transport to obtain access to this serialization.</li>
<li>Repeat as many times as desired.</li>
</ul>
<p >I.e., a message &ndash; once mutated and serialized/sent &ndash; can be re-sent as many times as desired. The concept implementer shall strive to make <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> be reasonably performant on the 2nd, 3rd, ... call. While all capnp serializations are zero-copy (before copying into transport), no particular care should be required to accomplish this; at worst it's a matter of grabbing the segment pointers and emitting them into a user-provided target container. There typically will be only a few; with SHM-based builders just one.</p>
<p >Lastly, then, the read/write lifecycle continuation is as follows:</p><ul>
<li>(Only if it is a SHM-based serialization) Receive some guarantee that the recipient is done reading the deserialization (e.g., an ack message).<ul>
<li>If it is not SHM-based, then this is not necessary: The deserialization is fully a copy of <code>*this</code> serialization, so mutating the original has no effect on the recipient.</li>
<li>(Wait, what? SHM-based? Yes: See "Copying versus zero-copy" section below.)</li>
</ul>
</li>
<li>Further mutate the payload <code>MessageBuilder</code> (as accessed via <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a>).</li>
<li>Call <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> again.</li>
<li>Transmit the emitted <code>Blob</code>s into some transport (the same one, a different one, whatever) &ndash; again.</li>
<li>Again use the counterpart <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> on the other side of this transport to obtain access to this serialization.</li>
<li>Repeat as many times as desired.</li>
</ul>
<p >I.e., it is much like the read-only variant above, except in a SHM-based builder variety one must take concurrent read/write access into consideration.</p>
<h3>Copying versus zero-copy</h3>
<p >You may note that the above unapologetically declares that the serialization's blobs must be <em>copied</em> into the transport. Isn't this a bad requirement? Isn't it bad to copy the entirety of the serialization? Answer: yes, it's bad, but consider what it means to copy the <em>entirety</em> of a serialization. Imagine a wacky scenario where an impl of this concept leverages the file system to store the serialization on disk, since disk has lots of storage capacity. It would be very bad to copy the contents of the disk file into the transport (and hence out of it, at the opposing end): it would destroy the whole point of storing on disk to begin with... but: One could, instead of copying the <em>contents</em> of the disk file, copy the file's name into the transport (and on the other side, read the file based on the received name).</p>
<p >That is to say: The impl may (and indeed, for at least some important applications, should/must) store the actual "inner" serialization (the one being mutated via mutators called on <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a></code>) in bulk where it wants; for example in shared memory. <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> can/should then emit segments (ideally, just one &ndash; and a small one for that matter) comprised by the "outer" serialization, which conceptually might be a handle referencing the (more-persistent) location of the "inner" (actual) serialization. This has the following important constraints:</p><ul>
<li>This outer (emitted by <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a>) serialization by definition must still be a capnp-<code>struct</code>.<ul>
<li>The inner one, too, must still be a capnp-<code>struct</code>.</li>
</ul>
</li>
<li>The inner serialization's lifetime must exceed that of <code>*this</code> to be of any use! Otherwise the "handle" in the outer serialization will be potentially useless by the time <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> counterpart tries to access it.<ul>
<li>This requirement is no joke: obviously it's necessary; but it means one must worry about cross-process cleanup of the resources (such as SHM-allocated buffer(s)) used up by the inner serialization.</li>
</ul>
</li>
</ul>
<p >To be clear, this inner-vs-outer serialization paradigm is <em>not</em> required. It is entirely reasonable, for some applications, to encode everything into the outer (required) serialization and not use any indirection or inner serialization at all. (<a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a> &ndash; the simplest of all &ndash; does just that and is basically the same as <code>MallocMessageBuilder</code>.) The benefit is clear: there's no cross-process cleanup, and the internal code is just much simpler. Conversely the negative is clear: copying large things may be expensive or even impossible (depending on the transport).</p>
<p >Both have their place. In practice, some special-use channels may use a deliberately simple schema with small, scalar-composed payloads. Then an outer-serialization-only impl (<a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a>, say) is perfect. When this is not so, use a more complex one (typically, we think, one based on SHM; see <a class="el" href="classipc_1_1transport_1_1struc_1_1shm_1_1Builder.html" title="Implements Struct_builder concept with maximal zero-copy perf by (1) storing the actual user-schema-c...">shm::Builder</a>).</p>
<h3>Allocation and perf</h3>
<p >For this section, please assume we are dealing with a simple (outer-serialization-only/fully-copied) impl of <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a>. The most obvious impl that comes to mind is one that, each time capnp requests a new segment of a certain minimum size, simply allocates on the regular heap. That's what <code>MallocMessageBuilder</code> does, and similarly <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a> does so as well.</p>
<p >That's fine. However, in advanced cases, it is conceivable to want more performance. Regular-heap allocation, depending on the size and underlying allocator impl (tcmalloc/jemalloc/ptmalloc...), can be somewhat expensive. In avoiding heap-allocation one could use other systems: memory pools; or even just a single pre-allocated area to be reused by <em>every</em> new <code>*this</code>. Let's briefly think about each of those.</p>
<p >Pools: This is not too different from a regular-heap allocator like <a class="el" href="classipc_1_1transport_1_1struc_1_1Heap__fixed__builder.html" title="Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in th...">Heap_fixed_builder</a>. It would just allocate from (insert pool library here). Heck, it could even use the shared-buffer functionality of a single <code>flow::util::Sharing_blob</code> to dole out memory chunks from a single heap-allocated buffer.</p>
<p >Single pre-allocated area to be reused by <em>every</em> new <code>*this</code>: This would be, of course, blindingly fast: probably <code><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a></code> would allocate a single <code>Sharing_blob</code> and each <code>*this</code> it created would be told to use that blob, no questions asked. The problem, obviously, is that 2+ <code>*this</code>es might step on each other concurrently. I.e., any use of this would basically require a pattern wherein a <code>*this</code> is created, mutated, emitted, destroyed; <em>then</em> same for the next out-message; and so on. Then there is no problem. Simply put, then: it is reasonable to develop such an impl of <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a> &ndash; if one requires the user to carefully ensure each out-message is entirely handled before work on the next one begins. For some applications that may be reasonable.</p>
<p >Similar reasoning could be extended to 2-tier (zero-copy/SHM-based) impls of <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a>. Naturally however one would need to ensure the given payload is fully consumed by the opposing side (<a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a>) before creating the next <code>*this</code>; it is not enough for merely the local <code>*this</code> to be destroyed, as the underlying payload may be referred-to by a <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__reader.html" title="A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::Me...">Struct_reader</a> still. </p>
</div><h2 class="groupheader">Member Typedef Documentation</h2>
<a id="ab90424897efed06ffc6b0884761fb31f" name="ab90424897efed06ffc6b0884761fb31f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab90424897efed06ffc6b0884761fb31f">&#9670;&nbsp;</a></span>Session</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f">ipc::transport::struc::Struct_builder::Session</a> =  unspecified</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Type objects of which specify to <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> the opposing recipient for which the serialization is intended; <a class="el" href="structipc_1_1transport_1_1struc_1_1Null__session.html" title="Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder...">Null_session</a> if no information is necessary to specify this. </p>
<p >Informally: typically, in a non-zero-copy builder the serialization itself would contain all necessary information, hence this would be <a class="el" href="structipc_1_1transport_1_1struc_1_1Null__session.html" title="Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder...">Null_session</a>; zero-copy (SHM-based) builder needs to specify a non-empty type here. </p>

</div>
</div>
<h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="ad98eba0fc5a8b377253eac797a9a117e" name="ad98eba0fc5a8b377253eac797a9a117e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad98eba0fc5a8b377253eac797a9a117e">&#9670;&nbsp;</a></span>Struct_builder() <span class="overload">[1/2]</span></h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::struc::Struct_builder::Struct_builder </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html">Config</a> &amp;&#160;</td>
          <td class="paramname"><em>config</em></td><td>)</td>
          <td> const &amp;</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">explicit</span><span class="mlabel">delete</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Main ctor, creating a new builder according to the knobs in <code><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Config</a> config</code> arg. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">config</td><td><a class="el" href="structipc_1_1transport_1_1struc_1_1Struct__builder_1_1Config.html" title="Copy-ctible, copy-assignable, default-ctible type – informally, cheaply copyable and likely an aggreg...">Struct_builder::Config</a> storing the knobs controlling how <code>*this</code> will work. Disallow copy construction. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a2c413c604b1d6abf63ce1589367dd772" name="a2c413c604b1d6abf63ce1589367dd772"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2c413c604b1d6abf63ce1589367dd772">&#9670;&nbsp;</a></span>Struct_builder() <span class="overload">[2/2]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::struc::Struct_builder::Struct_builder </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-constructs <code>*this</code> to be equal to <code>src</code>, while <code>src</code> becomes as-if defaulted-cted. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Moved-from object that becomes as-if default-cted. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="af5085934123f075c6d0701e9e45e4bcc" name="af5085934123f075c6d0701e9e45e4bcc"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af5085934123f075c6d0701e9e45e4bcc">&#9670;&nbsp;</a></span>emit_serialization()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void ipc::transport::struc::Struct_builder::emit_serialization </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1transport_1_1struc.html#a82a69eaa39cbe8a002de1266f1cbb5cb">Segment_ptrs</a> *&#160;</td>
          <td class="paramname"><em>target_blobs</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f">Session</a> &amp;&#160;</td>
          <td class="paramname"><em>session</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns the serialization in the form of a sequence of 1+ pointers to <code>Blob</code>s which are guaranteed to remain valid and unchanged until <code>*this</code> is destroyed, or the contents are further mutated via <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a>. </p>
<p >These are <em>appended</em> to <code>*target_blobs</code>.</p>
<p >You may call this method more than once per <code>*this</code>. However, if it fails, <code>*this</code> shall be considered useless. Please read the concept doc header carefully regarding the context and proper use of calling <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> more than once.</p>
<p >The result (<code>*target_blobs</code> contents) is (generally) meaningless once <code>*this</code> is mutated further.</p>
<h3>Errors</h3>
<p ><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> may emit an error via standard (to Flow-IPC) semantics if the serialization procedure in some way fails. Mutations on <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#a9a4b9587c162f85ad4d3e0a5fad8dffb" title="Pointer to the payload Capnp_msg_builder_interface, suitable for mutation by the user.">payload_msg_builder()</a> shall be assumed to work and not throw or otherwise emit errors, outside of misuse of capnp or bugs in capnp. However <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> may report an error synchronously, even if internally it is known there is an error earlier than the <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> call itself.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">target_blobs</td><td>On success (no error emitted) this is appended-to with the sequence of pointers to segments as <code>Blob</code>s. </td></tr>
    <tr><td class="paramname">session</td><td>Specifies the opposing recipient for which the serialization is intended. If <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f" title="Type objects of which specify to emit_serialization() the opposing recipient for which the serializat...">Session</a> is <a class="el" href="structipc_1_1transport_1_1struc_1_1Null__session.html" title="Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder...">Null_session</a>, then <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#ab90424897efed06ffc6b0884761fb31f" title="Type objects of which specify to emit_serialization() the opposing recipient for which the serializat...">Session()</a></code> is the only value to supply here. Otherwise more information is necessary. </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ae1516b0d68c48f2e13baf6aca366ac6c" name="ae1516b0d68c48f2e13baf6aca366ac6c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae1516b0d68c48f2e13baf6aca366ac6c">&#9670;&nbsp;</a></span>n_serialization_segments()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">size_t ipc::transport::struc::Struct_builder::n_serialization_segments </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns what <code>target_blobs.size()</code> would return after calling <code>emit_serialization(&amp;target_blobs)</code> (with an empty <code>target_blobs</code> going-in), right now. </p>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<a id="a708a66e9598c75a1f54828a4805da4f0" name="a708a66e9598c75a1f54828a4805da4f0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a708a66e9598c75a1f54828a4805da4f0">&#9670;&nbsp;</a></span>operator=()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp; ipc::transport::struc::Struct_builder::operator= </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html">Struct_builder</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-assigns <code>*this</code> to be equal to <code>src</code>, while <code>src</code> becomes as-if defaulted-cted; or no-op if <code>&amp;src == this</code>. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Moved-from object that becomes as-if default-cted, unless it is <code>*this</code>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>*this</code>. </dd></dl>

</div>
</div>
<a id="a9a4b9587c162f85ad4d3e0a5fad8dffb" name="a9a4b9587c162f85ad4d3e0a5fad8dffb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9a4b9587c162f85ad4d3e0a5fad8dffb">&#9670;&nbsp;</a></span>payload_msg_builder()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="namespaceipc_1_1transport_1_1struc.html#a52405569bf63eaef55f3c2435c885abc">Capnp_msg_builder_interface</a> * ipc::transport::struc::Struct_builder::payload_msg_builder </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Pointer to the payload <a class="el" href="namespaceipc_1_1transport_1_1struc.html#a52405569bf63eaef55f3c2435c885abc" title="Alias for capnp&#39;s MessageBuilder interface. Rationale: as part of our API, we use our identifier styl...">Capnp_msg_builder_interface</a>, suitable for mutation by the user. </p>
<p >Informally: we expect the outside use of some subset of the pointee methods <code>initRoot()</code>, <code>getRoot()</code>, <code>setRoot()</code>, <code>adoptRoot()</code>, <code>getOrphanage()</code> but <em>not</em> <code>getSegmentsForOutput()</code>. To access the serialization properly you must use <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a> instead. Otherwise you'd be foregoing the main point of <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">Struct_builder</a>'s existence which is to allow for a 2-tier serialization (as described in the concept doc header) and therefore true zero-copy end-to-end.</p>
<h3>Errors</h3>
<p >See <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html#af5085934123f075c6d0701e9e45e4bcc" title="Returns the serialization in the form of a sequence of 1+ pointers to Blobs which are guaranteed to r...">emit_serialization()</a>.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. Always returns the same pointer. </dd></dl>

</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>transport/struc/<a class="el" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2serializer_8hpp.html">serializer.hpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:23 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
